feat(bridge): bridge, then buy from the token page - #126

Phase 4 of the bridge update. Stacked on #125 (transfer history), and the base branch retargets as the lower PRs merge.

What it does

A buyer on a token page who is short of what the buy pays with now gets a two-step card in the trade panel: 1. bridge, 2. buy. These stay two separate wallet prompts. An atomic bridge-and-buy is out of scope because a Relay destination call runs from Relay's contract, not the buyer's wallet, so it needs its own reviewed design.

• When it shows: buy side, wallet connected, token tradable, and the wallet holds none of the pay asset or less than the buy plus the gas reserve. Only pay assets the bridge delivers qualify: ETH on Base and Robinhood, USDC on Arc, USDC on Base, USDG on Robinhood. A token priced in TWIG, GITLAWB or another quote token shows nothing.
• Finds funds elsewhere: reads the wallet's balance of every bridge asset on every other bridge network, including Ethereum, Arbitrum and Optimism. It does this once per wallet and page while the buyer is short. A network that does not answer is left out and never counted as empty.
• Suggests one source: the largest holding worth at least $1 by value. With no ETH price, the largest of the buy's own kind, with an ETH floor of 0.0005. A token holding only counts beside ETH for gas on its network, except on Arc, where USDC is the gas.
• Opens the bridge on that route: network and asset at both ends, through the panel's guarded pickers. No amount is passed; the card says how much the buy is short.
• Follows the transfer: the newest transfer into this network from this browser's ledger (feat(bridge): transfer history on /bridge #125), from the last two hours, sent to this wallet and not hidden.
  • While it is unsettled, the card wakes the one bridge controller with the panel closed, so tracking continues.
  • On arrival, the trade panel reads its balances at once and step 2 says to buy above.
  • A refund, failure or unknown status sends the buyer to the bridge.
• Never makes a wallet call, sends anything, starts a second controller, or buys.

Changes

• lib/bridge/fund.ts (new, pure)
  • bridgeAssetForPay, readBridgeHoldings
  • pickBridgeSource, formatFundAmount
  • followedBridge, fundStep
• components/bridge/BridgeToBuy.tsx and Fund.module.css (new): the card, using the Signal-board plate, plus FundCard built from plain props for the fixture.
• BridgeProvider
  • useOpenBridge()(link?) opens the bridge on a route.
  • useWakeBridge() mounts the controller closed.
  • The context value is memoized.
  • A stale request is dropped once /bridge takes over.
• BridgeDialog: linkCount makes a repeated request for the same route apply again.
• TradePanel: computes the shortfall, adds refetchPay, and renders the card on the buy side.
• /ui-review-bridge: seven fund scenes. Tests: fund.test.ts (5) and a guard test in bridge-ui.test.ts. Docs: "Bridge, then buy" in docs/bridge.md.

Verification

• npm test: 1460 tests, 1384 pass, 48 skipped and 28 fail. The 28 failures are the same set as on main and are unrelated.
• tsc --noEmit is clean, and eslint on the changed files is clean.
• Browser: the /ui-review-bridge fund scenes look right on desktop and at 375px, in light and dark, with no overflow. /bridge still renders its panel and transfer board.
• Not exercised:
  • The real trade panel with a connected wallet. My local DB has no launches, and no wallet signed anything.
  • A real bridge-then-buy with small amounts. This is worth one manual pass before release.